Skip to main content

Recommendational AI

Description: The Recommendations provides personalized recommendations based on user behavior or preferences. Common use cases include product recommendations for e-commerce, event suggestions for ticketing platforms, or course/content recommendations for edtech applications. Under the hood, Outter’s Recommendation Service uses machine learning models (collaborative filtering, content-based filtering, or fine-tuned AI models) to suggest relevant items.

Endpoint: POST /api/v2/ai/recommendations/generate.

This endpoint generates recommendations for a given context. The request body typically contains information about the user or session, and any relevant context or filters. For example:

POST /api/v2/ai/recommendations/generate
Content-Type: application/json
Authorization: X-API-Key YOUR_API_KEY

{
  "user_id": "u7ef95ca7",
  "context": {
    "recently_viewed": ["prodc1d74b2a", "prod7f59c154"],
    "cart_items": ["prod8054fba6"]
  },
  "num_recommendations": 5
}

  • user_id (optional): Identifier for the end user. If provided, Outter may use the user's history or profile to tailor recommendations (could be linked to data integrated via the connector).
  • context: A JSON object with context data. This can vary by industry:
    • E-commerce: might include recently_viewed product IDs, cart_items, or past_purchases.
    • Event Ticketing: could include categories of interest, past events attended, or the current event a user is viewing (for which to recommend similar events).
    • EdTech: might include courses completed, skill level, or topics of interest.
  • num_recommendations: How many recommendations to return (default could be 3-5 if not specified).

Example Response:

{
  "user_id": "u7ef95ca7",
  "recommendations": [
    {
      "id": "prod2df9f03c",
      "name": "Wireless Noise-Canceling Headphones",
      "score": 0.92,
      "rank": 1,
      "type": "collaborative_filtering",
      "metadata": {
        "category": "Electronics",
        "reason": "Frequently bought together with items in your cart"
      }
    },
    {
      "id": "prod37eee43b",
      "name": "Portable Bluetooth Speaker",
      "score": 0.88,
      "rank": 2,
      "type": "content_based",
      "metadata": {
        "category": "Electronics",
        "reason": "You viewed similar items last week"
      }
    },
    {
      "id": "prod5fe9c679",
      "name": "Smart LED Desk Lamp",
      "score": 0.85,
      "rank": 3,
      "type": "trending",
      "metadata": {
        "category": "Home & Office",
        "reason": "Popular among customers in your location"
      }
    }
  ],
  "pagination": {
    "current_page": 1,
    "per_page": 3,
    "total_pages": 7,
    "total_recommendations": 20,
    "next_page": 2,
    "previous_page": null
  },
  "request_id": "c6e5c021",
  "model": "olivaw-r1",
  "usage": {
    "prediction_count": 20,
    "tokens_used": 378,
    "timestamp": "2025-03-13T14:49:00Z"
  }
}



In this response:

  • recommendations is a list of recommended items with an id, human-readable name, a relevance score, and optional metadata explaining the reasoning (if available).
  • request_id is a unique ID for tracking the request (useful for debugging or support).
  • model indicates the model or strategy used (for transparency, e.g., which algorithm or AI model).
  • usage: (Optional) information about this call's usage. Here we show an example of fields that might be included, such as a count of predictions or a timestamp. Actual usage details for billing are discussed in the Usage & Billing section.

Industry-Specific Notes:

  • E-commerce: Use this API to power "Related Products" or "Customers also bought" sections. Ensure you pass relevant context like the user's browsing history or cart contents. You can also filter recommendations by category or price range by including filter parameters in the request (if supported by Outter).
  • Event Ticketing: Use the API to recommend events based on genre or artist similarity. Passing a user's past attendance or favorite genres in context can yield better suggestions.
  • EdTech: Get learning content or course recommendations. Provide the user's skill level, completed courses, or learning goals. The recommendations could then be used to suggest the next course or content piece in a learning path.

Best Practice: Always log or store the request_id from the response along with what was shown to the user. This can help in reviewing recommendation quality and is useful if you need to troubleshoot with Outter support.